//! 
//! # Transport（传输层契约）
//! 
//! pubsub.rs
//! 
//! (RUST) alone
//! 
//! Create time: 2025-09-25		alone
//! Update time: 2025-09-25		alone
//!
//! 该模块定义网络“传输层”的**最小能力集合**：连接、发送、关闭，
//! 并提供聚合后的门面 trait `Transport` 便于上层依赖抽象、替换实现。
//!
//! 设计原则：
//! - **职责单一**：把能力拆成 `Connector`/`FrameSink`/`Shutdown`，便于按需实现与单测。
//! - **无运行时耦合**：不在契约里暴露 Tokio/async-std 细节（仅使用 `async fn`）。
//! - **并发安全**：`Transport` 要求实现者满足 `Send + Sync`，便于多任务共享。
//! - **对象安全**：方法签名不带泛型参数，支持 `Arc<dyn Transport>` 动态分发。
//!
//! 命名说明：
//! - 没用 `Send` 作为“发送能力”的名字，避免与 `std::marker::Send` 混淆；
//! - 如果你的语义是“消息/命令”，可把 `FrameSink` 改名为 `MessageSink` 并让其参数为高层类型。
//!
//! 典型用法：
//! ```ignore
//! use std::sync::Arc;
//! use crate::common::transport::{Connector, FrameSink, Shutdown, Transport};
//!
//! async fn run(t: Arc<dyn Transport>) -> anyhow::Result<()> {
//!     t.connect().await?;
//!     t.send(b"hello").await?;  // 按帧/字节发送（由实现定义粘/拆包）
//!     t.close().await?;
//!     Ok(())
//! }
//! ```
//!
//! 扩展点：
//! - 若需要订阅事件（`Connected/Disconnected/Message` 等），请在**另一个模块**定义
//!   通用 `Subscribe` trait（返回 `Stream` 或 Tokio `broadcast::Receiver`），
//!   然后让具体实现同时实现本模块与 `Subscribe`。
//! - 若需要编解码，定义 `Codec` trait（`encode/decode`），由上层组合使用。
//!
//! 错误处理：
//! - 这里统一使用 `anyhow::Result<()>`（或你项目的 `Result<(), Error>`）；
//!   生产环境建议自定义错误类型以区分 IO/协议/超时等。
//! 

use anyhow::Result;

/// 连接能力：建立到底层对端的会话。
///
/// 典型实现：TCP `connect`、TLS 握手、WebSocket 握手、QUIC 建连等。
#[allow(async_fn_in_trait)]
pub trait Connector 
{
    /// 发起连接；幂等实现应允许在已连接状态下返回 `Ok(())` 或执行重连。
    async fn connect(&self) -> Result<()>;

	fn is_connected(&self) -> bool;
}

/// 发送能力：将一帧/一段字节写入会话。
#[allow(async_fn_in_trait)]
pub trait FrameSink 
{
    /// 发送一帧数据。实现应负责必要的粘/拆包或长度前缀。
    async fn send(&self, frame: &[u8]) -> Result<()>;

	/// 接受数据并发送出去
	async fn recv(&self) -> Result<()>;
}

/// 关闭能力：有序关闭会话并回收资源。
///
/// - 实现可选择半关闭/全关闭；重复调用应安全（幂等）。
#[allow(async_fn_in_trait)]
pub trait Shutdown 
{
    /// 关闭连接；要求可重入且不 panic。
    async fn close(&self) -> Result<()>;
}

/// 聚合后的“传输层”能力门面：
///
/// - 组合了连接/发送/关闭三种能力；
/// - 额外要求实现者 `Send + Sync` 以支持跨任务共享；
pub trait Transport: Connector + FrameSink + Shutdown + Send + Sync {}

impl<T> Transport for T where T: Connector + FrameSink + Shutdown + Send + Sync {}